Ham Radio 2000

home *** CD-ROM | disk | FTP | other *** search

/ Ham Radio 2000 / Ham Radio 2000.iso / ham2000 / satellit / pacdoc / fhead.doc < prev next >

Wrap

Text File | 1990-09-05 | 25KB | 656 lines

Pacsat File Header Definition Jeff Ward, G0/K8KA Harold E. Price, NK6K ABSTRACT A flexible encoding method for PACSAT file headers is described, and ``Mandatory'', ``Extended'' and ``Optional'' Headers are defined. These headers are supplied by the programs which send files and/or messages to PACSAT, and by on-board programs which build files/messages intended for downloading. PACSAT file head- ers are present in all files stored on PACSAT. 1.0 BACKGROUND PACSAT is a file and message switch, a BBS and a data generating device. Files may be generated by onboard processes such as telemetry gathering pro- grams, SEU monitor programs, or imaging cameras. Files will also be used to hold the messages in the PACSAT on-board BBS. Files and messages will be sent and received by many nodes: forwarding gateways, individual user stations, command stations, and various on-board tasks. To conserve on-board storage space and communications link time, files may be compressed by a variety of compression methods. To ensure that these files can be properly identified and processed, each file stored on PACSAT will begin with several header items. Some header items will be present on every PACSAT file; these are described below as the Mandatory Header. Another group of items must be present on all files which contain ``messages''; these are described as the Extended Header. Additional special- purpose or user-defined items are described under the Optional Header. The primary objectives of the PACSAT File Header standard are to (1) encode all header items in a standardized manner; (2) maintain complete separation between the file/message header and the file/message body; (3) provide for expansion through easy incorporation of additional header items. 1.1 Overview of the PACSAT File Header System Every PACSAT file will start with the byte 0xaa followed by the byte 0x55. This flag is followed by the rest of the PACSAT File Header (PFH). A valid PFH contains all of the items of the Mandatory Header (Section 3), and it may also contain all items of the Extended Header (Section 4) and any number of Optional Header items (Section 5). All HEADER ITEMS are encoded using a standard syntax, described in Section 2. The PFH is terminated by a special header item, after which the file body begins. Thus, there are 3 forms of PACSAT file header: <0xaa><0x55><Mandatory hdr><Hdr end> <0xaa><0x55><Mandatory hdr><Extended hdr><Hdr end> <0xaa><0x55><Mandatory hdr><Extended hdr>[<Optional Items> . . . ]<Hdr end> 2.0 PACSAT HEADER ITEM SYNTAX All PACSAT file header items follow a single format, simplifying both specifi- cation and implementation of the PACSAT File Header. The format is: <id><length>[<data> . . . ] 2.1 <id> The id is a 2-byte integer in which the bits have the following meaning: bit 15 0 this is an system-defined item. 1 this is an experimental, user defined item. bits 0-14 form the 15-bit unsigned binary number identifying the item. The <id>, allows some 32,000 system-defined and 32,000 user defined items. <id> like all multi-byte integers is stored least-significant byte first. Refer to the PACSAT Data Specification Standards document for further informa- tion. 2.2 <length> This field is an 8-bit unsigned binary integer giving the number of <data> bytes present. Even if the size of the data item is fixed, the length is still present. 2.3 <data> The <data> bytes may hold any type of information. Encoding rules for system-defined items are found in this document. User- defined items may adopt any internal encoding agreed by all users of the item. 2.4 Presentation The PACSAT File Header must always be transmitted without data compression, even if compression is applied to the body of the attached file. 2.5 Header Termination The end of the PACSAT File Header will always be indicated by a header item with <id> 0 and <length> 0. The byte sequence is 0x00 0x00 0x00. 3.0 THE PACSAT MANDATORY HEADER The first two bytes of a PACSAT file should always contain 0xaa followed by 0x55 to confirm that the file contains a PACSAT file header. The 0xaa, 0x55 sequence must be followed immediately by all items of the Mandatory Header. Mandatory Header items must be present in order of ascending value of <id>. When preparing files for uploading to PACSAT, groundstations must initialize header items as specified below. 3.1.1 file_number id : 0x01 length : 4 data : unsigned long file_number <file_number> is a 4-byte unsigned serial number assigned to a file by PACSAT when the file is created. This number uniquely identifies any file. Since the PACSAT file system makes no distinction between files and ``mes- sages'', the file number is analogous to a message serial number. INITIALIZATION - Must be initialized to 0. 3.1.2 file_name id : 0x02 length : 8 data : char file_name[8] <file_name> is the base name of the file as it is stored in the PACSAT file system. If the name is shorter than 8 characters, it is extended on the right with ASCII spaces (0x20). INITIALIZATION - Must be initialized to 8 ASCII spaces (0x20), allowing PACSAT to choose its own name for the file. The <user_filename> Optional item can be used to communicate the file's native name to another user. 3.1.3 file_ext id : 0x03 length : 3 data : char file_ext[3] <file_ext> is a 3 character file name extension. If the extension is shorter than 3 characters, it is extended on the right with ASCII spaces (0x20). INITIALIZATION - Must be initialized to 3 ASCII spaces (0x20), allowing PACSAT to choose its own name for the file. The <user_filename> optional item can be used to communicate the file's native name to another user. 3.1.4 file_size id : 0x04 length : 4 data : unsigned long file_size <file_size> is a 4-byte unsigned integer indicating the total number of bytes in the file, including the HEADER_FLAG, all HEADER_FIELD structures, and the file body. INITIALIZATION - Correct <file_size> must be provided. 3.1.5 create_time id : 0x05 length : 4 data : unsigned long create_time <create_time> is a 4-byte unsigned integer time-stamp telling when the file was created. This time-stamp counts the seconds since Jan 1, 1970. INITIALIZATION - If <create_time> is initialized to 0, PACSAT will set the time upon receiving the file header. Otherwise PACSAT does not alter this item. 3.1.6 last_modified_time id : 0x06 length : 4 data : unsigned long last_modified_time INITIALIZATION - If <last_modified_time> is initialized to 0, PACSAT will set the time upon receiving the file header. Otherwise PACSAT does not alter this item. 3.1.7 seu_flag id : 0x07 length : 1 data : unsigned char seu_flag Files stored on PACSAT may experience Single-Event Upsets, caused by radia- tion. <seu_flag> is an unsigned 8-bit integer for which 3 values are current- ly defined: 0 means there have been no Single Event Upsets detected in this file. 1 means that one or more correctable Single Event Upsets have occurred and been corrected in this file. It will be possible, though unlikely, that mul- tiple SEU-caused bit errors in a file block will cause an improper correction. An overall file checksum is provided as additional protection. 2 means that an uncorrectable corruption was detected in this file. INITIALIZATION - this item must be initialized to 0. 3.1.8 file_type id : 0x08 length : 1 data : unsigned char file_type <file_type> is an unsigned 8-bit integer indicating what type of data is presented in the file body. Values for this item are defined in a separate document. The value 0xff is reserved as an escape indicator, in which case an Optional item of type <file_description> must be provided. INITIALIZATION - this item must be appropriately initialized. NOTE - It is intended that this item be used to limit the scope of message searches, therefore, values will be defined for important types of files such as: RLI/MBL compatible single messages, RLI/MBL compatible import files, VITA- only messages, etc. See Appendix A for details. 3.1.9 body_checksum id : 0x09 length : 2 data : unsigned int body_checksum A 16 bit checksum formed by adding all bytes in the file body into a 16 bit variable, ignoring overflow. The <body_checksum> does not include the bytes comprising the PACSAT file header. The <body_checksum> is primarily intended to detect mis-corrected multi-bit errors caused by Single Event Upsets in the PACSAT memory. INITIALIZATION - The correct <body_checksum> must be supplied. 3.1.10 header_checksum id : 0x0a length : 2 data : unsigned int header_checksum A 16 bit checksum formed by adding ALL bytes in PACSAT File Header, including the leading 0x55 0xaa sequence, into a 16 bit variable, ignoring overflow. This number is then stored as the <header_checksum>. When calculating the sum the 2 <header_checksum> data bytes are assumed to be 0, and the <body_check- sum> must have already been calculated. The <header_checksum> is primarily intended to confirm correct header recep- tion during file transfers. INITIALIZATION - the <header_checksum> must be correctly initialized. 3.1.11 <body_offset> id : 0x0b length : 2 data : unsigned int body_offset <body_offset> provides the byte offset of the first byte of the file body. <body_offset> is taken with respect to the first byte of the file, which has offset 0. The byte at offset 0 contains the 0xaa marking the beginning of the PFH. Note also that <body_offset> is equal to the length of the PFH, in bytes. INITIALIZATION - <body_offset> must be correctly initialized. 3.2 Mandatory Header Summary The PFH Mandatory header will be present on every PACSAT file. When preparing to upload a file or message to PACSAT, groundstation software must create a valid Mandatory header and insert it at the beginning of the file/message. 4.0 THE PACSAT EXTENDED HEADER The PACSAT Mandatory Header defined above is designed for file transfer. It contains sufficient information to reliably upload and download PACSAT files, including transfers spread over several satellite passes. It does not contain all the header fields which are desirable for forwarding BBS messages or for implementing a complex PACSAT end-user message system. The additional header fields needed for these tasks are placed in the PACSAT file after the Mandato- ry Header. A standard set of message-related header fields called the PACSAT Extended Header is described in this section. All message files uploaded to PACSAT should contain both the Mandatory and Extended headers. If a Extended Header is present, it must immediately follow the final item in the Mandatory Header. If any Extended Header item is present, all must be present. Extended Header items must be present in order of ascending value of <id>, with the exception that multiple destinations are represented by multiple occurrences of items 0x14, 0x15, and 0x16. 4.1 Extended Header Summary The Extended Header provides necessary information concerning the source and destination of a message file. Source data is encoded in a variable-length <source> item, which can contain any type of identifier. The AX.25 address of the station which uploaded the message is also provided, along with the time at which the upload was completed. Destination data is provided in the same format, and provisions are made to allow a single message file to have several specified destinations. Three other items useful for PACSAT message handling are defined: compression_technique, expire_time, and priority. 4.2.1 source id : 0x10 length : variable data : char source[] <source> is an ASCII string used to identify the originator of the file/mes- sage. <source> can be a mixed-case string, containing any character from 0x20 to 0x7e. INITIALIZATION - This item should contain the address of and possibly the route to the file originator. Exact details of the use for this item must be agreed among parties using PACSAT for message forwarding. Stations using PACSAT as their ``home BBS'' are requested to use the form <call> @ OSCAR<num>, e.g. G0K8KA @ OSCAR14. VITA will devise its own addressing scheme, which should be used by VITA groundstation software. 4.2.2 ax25_uploader id : 0x11 length : 6 data : char ax25_uploader[] Contains the ax.25 address of the station which uploaded the file. The SSID is not included in this address. If the callsign is less than 6 characters long, it will be filled to 6 characters by appending spaces (0x20) on the right. INITIALIZATION - No initialization required. 4.2.4 upload_time id : 0x12 length : 4 data : unsigned long upload_time This field tells the time at which the upload was completed. If the upload is still in progress, upload_time will be 0x0000. <upload_time> is an unsigned integer counting the number of seconds since 0000 UTC Jan 1, 1970. INITIALIZATION - Must be set to 0. 4.2.5 download_count id : 0x13 length : 1 data : unsigned char download_count <download_count> is an 8-bit unsigned integer incremented each time the asso- ciated file is successfully downloaded. INITIALIZATION - set to 0. 4.2.6 destination id : 0x14 length : variable data : char destination[] <destination> is an ASCII string used to identify the originator of the file/message. <destination> can be a mixed-case string, containing any char- acter from 0x20 to 0x7f. INITIALIZATION - PACSAT makes no attempt to interpret this item. It must be initialized to an address which will be recognized by the station intended to download the message. When addressing messages to stations using PACSAT as a ``home bbs'', please use <callsign> @ OSCAR<num>, e.g. NK6K @ OSCAR16. 4.2.7 ax25_downloader id : 0x15 length : 6 data : char ax25_downloader[6] <ax25_downloader> is the ASCII address of the groundstation which has down- loaded this file for the recipient specified in the immediately preceding <destination> item. A <destination> item must be immediately followed by an <ax25_downloader> item. INITIALIZATION - Must be initialized to six ASCII blanks - 0x20. 4.2.8 download_time id : 0x16 length : 4 data : unsigned long download_time <download_time> is the time at which the message was completely downloaded by the immediately preceding <ax25_downloader> groundstation. <download_time> is an unsigned integer counting the number of seconds since 0000 UTC January 1, 1970. An <ax25_downloader> item must be immediately followed by a <download_time> item. INITIALIZATION - Set to 0. NOTE - A message may have several intended destinations. For each destina- tion, the PFH Extended header must contain header items 0x14, 0x15 and 0x16. Multiple destinations are numbered in the order of occurrence; the first <destination> <ax25_downloader> <download_time> set is destination 0, the next destination 1, etc. 4.2.11 expire_time id : 0x17 length : 4 data : unsigned long expire_time <expire_time> is the time after which this file should be considered inactive. As with other timestamps, this field is an unsigned long integer counting seconds since Jan 1, 1970. Expired files may be purged by the PACSAT when more free file space is needed. INITIALIZATION - Groundstations may set this field in uploaded files, or may leave it set to 0. If a groundstation-selected <expire_time> is within system limits, it will be retained, otherwise the PACSAT will choose its own <expire_time>. 4.2.12 priority id : 0x18 length : 1 data : unsigned char priority This field carries the message priority field. Higher numbers are considered higher priority than lower numbers. INITIALIZATION - The groundstation must initialize this field. Groundstation software should exercise some control over the user's abuse of this field, so that it retains some meaning in operation! Over use of high priorities re- duces the utility of this field. 5.0 OPTIONAL HEADER ITEMS The Mandatory Header and Extended Header may be followed by any number of Optional Header items. It is intended that any expansion of the PFH defini- tion will involve only addition of Optional Items Optional Header items need not be presented in increasing order of <id>. 5.1 System-defined Optional Header Fields 5.1.1 compression_type id : 0x19 length : 1 data : unsigned char compression_technique The body of a PACSAT message may be compressed to reduce the communications bandwidth and on-board storage required for the message. Groundstations, and not PACSAT, must compress and de-compress PACSAT files. The <compression_type> item is a 1-byte unsigned binary integer. Values are available for assignment to common compression schemes. <compression_type> 0xff is reserved as an escape code indicating that additional information is to be found in a <compression_description> item. Currently assigned values can be found in Appendix B. INITIALIZATION - If present, must be correctly set by the uploading station. 5.1.1 bbs_message_type id : 0x20 length : 1 data : char bbs_message_type This field carries the single ASCII character used to indicate message type on RLI/MBL BBS messages. 5.1.2 bulletin_id_number id : 0x21 length : variable data : char bid[] The <bid> item holds an ASCII string uniquely identifying the file/message. This field is used by terrestrial BBSs to stop the duplication of flood bulle- tins. INITIALIZATION - PACSAT will not itself initialize <bid> on an uploaded file. It is the responsibility of the uploading station to initialize this field, if the message is a bulletin intended for introduction into the Amateur Radio PBBS network. 5.1.3 title id : 0x22 length : variable data : char title[] This field carries the ASCII string message title. Most messages will have a <title>, initialized by the user to indicate the contents of the message. In some systems, this is called the Subject. 5.1.4 keywords id : 0x23 length : variable data : char keywords[] This field carries one or more ASCII keywords describing the file/message. Multiple keywords must be separated by at least one ASCII space character (0x20). 5.1.5 file_description id : 0x24 length : variable data : char file_description[] The <file_description> item is used only if none of the system standard <file_type> values can adequately describe the file body. A <file_description> item is up to 255 ASCII characters describing the format of the file body. This field must be included if the <file_type> field in the Mandatory Header is set to 0xff. For example, an uploading station might set the <file_type> to 0xff and <file_description> to ``This body contains all of the files associated with a Ventura Publisher document''. 5.1.6 compression_description id : 0x25 length : variable data : char compression_description[] A compression_description item is used when a non-standard method of file-body compression has been used. The item is up to 255 ASCII characters describing the method or (preferably) providing a reference to further information concerning the method. The field must be present when compression_technique in the fixed portion of the Extend- ed File Header is set to 0xff. For example, an uploading station might set compression_technique 0xff and compression_description to ``Compressed using bmpack version 1.4, see file with title = ``BMPACK specification''. 5.1.7 user_file_name id : 0x26 length : variable data : char user_file_name[] This field is used by groundstations using PACSAT as a file switch to transfer named files. The originating station places the desired file name in a user_file_name field, and the destination station uses this field as the name of the file after it has been received. This field is included in addition to the file_name field because the file_name field is strictly constrained by PACSAT (e.g. no two files may have the same file_name, and the name must be no longer than 8 characters with a 3 character extension). The file_name is used by PACSAT for internal purposes, and this item, user_file_name is used for end-to-end transparent communication of a file name. 6.0 Implementation Status Files with these headers are currently in use on the PACSATs. Additional system header items may be added from time to time, as well as file and com- pression types. To suggest new standard items, contact the authors. Address comments to: Telemail: HPRICE or UOSAT Compuserve: 71635,1174 Packet: NK6K @ WB6YMH or G0K8KA @ GB2UP Internet: 71635.1174 @COMPUSERVE.COM Mail: Jeff Ward UoSAT Unit University of Surrey Guildford, Surrey GU2 5XH UK APPENDIX A - PACSAT FILE TYPES Unless explicitly stated, a file of any <file_type> can have a compressed body. If the body is compressed, its PFH must contain the optional <compres- sion_type> item. The PFH is never compressed. 0x00 ASCII text file intended for display/printing. Not Com- pressed. 0x01 RLI/MBL message body. Single message. 0x02 RLI/MBL import/export file. Multiple message. 0x03 UoSAT Whole Orbit Data 0x04 Microsat Whole Orbit Data 0x05 UoSAT CPE Data 0x06 MS/PC-DOS .exe file 0x07 MS/PC-DOS .com file 0x08 Keplerian elements NASA 2-line format 0x09 Keplerian elements ``AMSAT'' format 0x0a Simple ASCII text file, but compressed. 0xff ESCAPE - indicates that the message header includes a varia- ble- length body_description item (see below) describing the body type, or providing a reference for further information. This code will be used for new techniques, until they can be assigned a formal identifier. APPENDIX B - PACSAT COMPRESSION TYPES (PROPOSED) 0x00 body not compressed 0x01 body compressed using PKARC 0x02 body compressed using PKZIP There is no intent to limit compression types to the IBM-PC. The prototype implementation of the ground station software is PC based.